Summary

Every failed MCP tool call currently records $mcp_error_type = "Error", so a stale session id, an org hitting its concurrency limit, and a fault on our side are indistinguishable in analytics. This names them.

toolErrorResponse becomes throwToolError, which throws instead of returning an isError result. The thrown error's name carries the Kernel API status — KernelApiError404, KernelApiError429, KernelApiError502 — or the SDK error class for transport failures (APIConnectionTimeoutError).

Why this works

The analytics SDK reads the error category from a thrown error's name. A returned isError result has no error object, so it coerces from the result text and always lands as a generic Error. That's why the existing data has exactly one error type.

Because throwToolError is the single funnel for caught API errors, the split falls out with no per-call-site logic:

• KernelApiError<status> — the Kernel API rejected the request.
• Error — the tool itself rejected the call (missing session_id, conflicting arguments, invalid config), which never reaches the API.

Agents see no change

The MCP SDK converts a thrown error back into the same isError text result, and the message string is byte-identical to what the helper produced before. Verified against the real API:

• manage_browsers get with an unknown session id → Error in manage_browsers (get): 404 browser session '...' not found, isError: true
• manage_browsers get with no session id → Error: session_id is required for get action., isError: true

Privacy

Status codes only. No message, parameters, or response are captured — confirmed on the captured events — and no $exception events are emitted. $mcp_error_type is already on the send allow-list, so nothing new is added to what leaves the server.

Verification

Ran the route locally against the production API and checked the captured events:

tsc --noEmit and prettier --check pass on every touched file.

Follow-up, deliberately not here

The generic Error bucket still mixes several kinds of tool-side rejection (missing argument vs conflicting arguments vs invalid config). Naming those too is mechanical but touches ~95 call sites, so it belongs in its own change if the split turns out to be worth it.